28.3.1.1 Looking Up Identifiers

The most important thing that xref enables you to do is to find the definition of a specific identifier.

M-.

Find definitions of an identifier (xref-find-definitions).

C-M-. pattern RET

Find all identifiers whose name matches pattern (xref-find-apropos).

C-x 4 . RET

Find definitions of identifier, but display it in another window (xref-find-definitions-other-window).

C-x 5 . RET

Find definition of identifier, and display it in a new frame (xref-find-definitions-other-frame).

M-,

Go back to where you previously invoked M-. and friends (xref-pop-marker-stack).

M-. (xref-find-definitions) shows the definitions of the identifier at point. With a prefix argument, or if there’s no identifier at point, it prompts for the identifier. If the identifier has only one definition, the command jumps to it. If the identifier has more than one possible definition (e.g., in an object-oriented language, or if there’s a function and a variable by the same name), the command shows the candidate definitions in a *xref* buffer, together with the files in which these definitions are found. Selecting one of these candidates by typing RET or clicking mouse-2 will pop a buffer showing the corresponding definition.

When entering the identifier argument to M-., the usual minibuffer completion commands can be used (see Completion), with the known identifier names as completion candidates.

Like most commands that can switch buffers, xref-find-definitions has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 . (xref-find-definitions-other-window), and the latter is C-x 5 . (xref-find-definitions-other-frame).

The command C-M-. (xref-find-apropos) finds the definitions of one or more identifiers that match a specified regular expression. It is just like M-. except that it does regexp matching of identifiers instead of matching symbol names as fixed strings.

When any of the above commands finds more than one definition, it presents the *xref* buffer showing the definition candidates. In that buffer, you have several specialized commands, described in Xref Commands.

To go back to places from where you found the definition, use M-, (xref-pop-marker-stack). It jumps back to the point of the last invocation of M-.. Thus you can find and examine the definition of something with M-. and then return to where you were with M-,. M-, allows you to retrace your steps to a depth determined by the variable xref-marker-ring-length, which defaults to 16.